\chapter{Installation}
\label{chap:install}

While you can use Gantry just fine without Bigtop -- its code generation
framework -- that's not as much fun.  So, this chapter will explain how to
install both Gantry and Bigtop.

If you have any trouble installing either Gantry or Bigtop, please post
questions on the Gantry mailing list.  To join, visit
www.usegantry.org\index{web site, Gantry}\index{Gantry!web site}
and click on the Mailing List tab.

\section{Installing Gantry}

The current stable release of Gantry is available from CPAN.
Install it as
you would any CPAN module.  That is, either use the CPAN shell or proceed
manually.  Both approaches are described below.

Whether you install via the CPAN shell or manually, you'll need to install
the prerequisites for the tests to pass.  The prerequisites list is
intentionally small, to allow for the greatest flexibility in deployment
options for you.  One module not on the list, which is highly useful, is
DBIx::Class.  Even if you don't have it at the outset, you can install
it later.  You'll need it to follow the examples in this book.

During Build.PL there is one prompt.  It asks:

{\footnotesize
\begin{verbatim}
Gantry comes with a set of default templates that
need to be written to disk. A typical location for these
templates is your web server document root.

Press enter to use the default directory or specify another
directory. [/home/httpd/html/gantry]
\end{verbatim}
}

You can take the default or supply your own, but your web server must be
willing to serve files from that directory.  Gantry will put all of its
default templates there.  This include the HTML form template for all of
its CRUD schemes, etc.  If the directory does not exist, Gantry's
installer will offer to create it with a second prompt.

During testing, you will be asked whether to run certain sets of tests.  The
questions ask whether you want to run tests against apparent
\verb+mod_perl+\index{mod perl@\verb+mod_perl+!gantry install tests}
installations.  A typical question looks like this:

{\footnotesize
\begin{verbatim}
# mod_perl version: 2.000001 detected
# Do you want to run mod_perl 2.000001 tests [yes]?
\end{verbatim}
}

\noindent
If you want to test against that installation answer yes (which is the
default).  If you know that the default \verb+mod_perl+
is not properly installed, or does not have a working \verb+libapreq+,
skip the test.

To use the CPAN shell type:

\begin{verbatim}
perl -MCPAN -e shell
cpan> install Gantry
\end{verbatim}

\noindent
This method is preferred, since it grabs the prerequisite modules for you.

If you like to work manually, you are welcome to download the gzipped tar
file, gunzip it, untar it, and install it by hand.  After it is untarred,
this reduces to:

\begin{verbatim}
perl Build.PL
./Build
./Build test
./Build install
\end{verbatim}

\section{Installing Bigtop}

The best place to get Bigtop is from CPAN.  Again, you can use the
CPAN shell or work manually.  In either case, life will go poorly if you
don't choose to install the prerequisite modules before testing.
Bigtop also asks questions during its installation process:

{\footnotesize
\begin{verbatim}
Bigtop has an editor called tentmaker.  It allows
you to edit bigtop files with a DOM compatible browser
(like Firefox).  tentmaker requires some templates.

Do you want to install the tentmaker templates? [y]
\end{verbatim}
}

Whether you answer yes or no, tentmaker\index{tentmaker!installing}
will be installed, but you won't be
able to use it without the templates.

If you wisely choose to answer yes, it will ask:

{\footnotesize
\begin{verbatim}
TentMaker needs to store some templates on your system.
Please choose a location for them.

Path for TentMaker templates [/usr/local/share/TentMaker]
\end{verbatim}
}

Choose any path you like, as long as the installing user has write permissions
to create it.  As with Gantry's installer, if the directory does not
exist, Bigtop's installer will offer to make it.

\section*{Summary}

Once you have installed Gantry and Bigtop, you'll want to build a small app
to get some feel for how these tools work.  That's the subject of the next
chapter.
